#
# overflowR: An R package to pull data from the StackOverflow API
# author: Shane Conway <shane.conway@gmail.com>
#
# This is released under a GPL license.
#
# Documentation was created using roxygen:
# roxygenize('overflowR', roxygen.dir='overflowR', copy.package=FALSE, unlink.target=FALSE)
#
###############################################################################

#' Get the number of pages per id.
#'
#' \code{num.pages} requests the total number of pages for a given class.
#'
#' @param type		Specifies the API data to return 
#' @param page.size	The number of records per page 
#' @return a numeric value for the number of pages
#' @keywords data
#' @author Shane Conway \email{shane.conway@@gmail.com}
#' @references
#' \url{http://stackapps.com/}
#' @seealso \code{\link{getSOData}} 
#' @examples
#' num.pages(type="tags")
num.pages <- function(type, page.size=100, ...) {
	ceiling((getSOData(type=type, page.size=0, ...)$total)/page.size)
}

#' Get a specific answer.
#'
#' \code{get.answer} returns a particular answer.
#'
#' @param id		The id for the answer 
#' @return data.frame containing the requested data
#' @keywords data
#' @author Shane Conway \email{shane.conway@@gmail.com}
#' @references
#' \url{http://stackapps.com/}
#' @seealso \code{\link{getSOData}} 
get.answer <- function(id) {
	1 # placeholder
}

#' Recursively get data from the API.
#'
#' \code{get.users} pulls a list of users.
#'
#' @param top.n		A specific record id (e.g. for a user) 
#' @param ...		Any other arguments for getSOData
#' @return data.frame containing the requested data
#' @keywords data
#' @author Shane Conway \email{shane.conway@@gmail.com}
#' @references
#' \url{http://stackapps.com/}
#' @seealso \code{\link{getSOData}} 
#' @examples
#' users <- get.users(50)
get.users <- function(top.n=NULL, ...) {
	get.recursive.data(type="users", top.n=top.n, ...)
}

#' Recursively get data from the API.
#'
#' \code{get.questions} pulls a list of questions.
#'
#' @param top.n		A specific record id (e.g. for a user) 
#' @param ...		Any other arguments for getSOData
#' @return data.frame containing the requested data
#' @keywords data
#' @author Shane Conway \email{shane.conway@@gmail.com}
#' @references
#' \url{http://stackapps.com/}
#' @seealso \code{\link{getSOData}} 
#' @examples
#' questions <- get.questions(50)
get.questions <- function(top.n=NULL, ...) {
	get.recursive.data(type="questions", top.n=top.n, ...)
}

#' Recursively get data from the API.
#'
#' \code{get.questions} pulls a list of questions tagged with specific tag
#'
#' @param top.n		A specific record id (e.g. for a user) 
#' @param tagged	A tag that returned questions must have
#' @param ...		Any other arguments for getSOData
#' @return data.frame containing the requested data
#' @keywords data
#' @author Miron Kursa \email{M.Kursa@@icm.edu.pl}
#' @references
#' \url{http://stackapps.com/}
#' @seealso \code{\link{getSOData}} 
#' @examples
#' questions <- get.questions(50)
get.tagged.questions <- function(tagged, top.n=NULL, ...) {
	get.recursive.data(type="questions", top.n=top.n, tagged=tagged, ...)
}

#' Recursively get data from the API.
#'
#' \code{get.tags} pulls a list of tags.
#'
#' @param top.n		A specific record id (e.g. for a user) 
#' @param ...		Any other arguments for getSOData
#' @return data.frame containing the requested data
#' @keywords data
#' @author Shane Conway \email{shane.conway@@gmail.com}
#' @references
#' \url{http://stackapps.com/}
#' @seealso \code{\link{getSOData}} 
#' @examples
#' tags <- get.tags(50)
get.tags <- function(top.n=NULL, ...) {
	get.recursive.data(type="tags", top.n=top.n, ...)
}

#' Recursively get data from the API.
#'
#' \code{get.recursive.data} is a basic function to recursively pull data from the API.
#'
#' @param type		Specifies the API data to return 
#' @param top.n		A specific record id (e.g. for a user) 
#' @param ...		Any other arguments for getSOData
#' @return data.frame containing the requested data
#' @keywords data
#' @author Shane Conway \email{shane.conway@@gmail.com}
#' @references
#' \url{http://stackapps.com/}
#' @seealso \code{\link{getSOData}} 
#' @examples
#' get.recursive.data(type="tags", top.n=5)
#' get.recursive.data(type="tags", site="stats.stackexchange", top.n=5)
get.recursive.data <- function(type, top.n, ...) {
	n <- if(is.null(top.n)) num.pages(type, ...) else ceiling(top.n/100)
	x <- ldply(1:n, function(i, ...) {
				ldply(getSOData(type=type, page.num=i, ...)[[type]], data.frame)
			}, ...=...)
	head(x, top.n)
}
